package com.example.api;

import com.example.entity.User;
import com.github.lianjiatech.retrofit.spring.boot.core.RetrofitClient;
import com.github.lianjiatech.retrofit.spring.boot.retry.Retry;
import retrofit2.Call;
import retrofit2.http.*;

import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * 用户 API 接口
 * 演示 Retrofit 的各种注解用法
 * 
 * @author example
 * @since 2024-01-01
 */
@RetrofitClient(baseUrl = "${external.api.jsonplaceholder.base-url}")
public interface UserApi {

    /**
     * 获取所有用户
     */
    @GET("/users")
    Call<List<User>> getUsers();

    /**
     * 根据 ID 获取用户
     * 
     * @param id 用户 ID
     * @return 用户信息
     */
    @GET("/users/{id}")
    Call<User> getUser(@Path("id") Long id);

    /**
     * 异步获取用户（支持 CompletableFuture）
     * 
     * @param id 用户 ID
     * @return 用户信息的异步结果
     */
    @GET("/users/{id}")
    CompletableFuture<User> getUserAsync(@Path("id") Long id);

    /**
     * 创建用户
     * 
     * @param user 用户信息
     * @return 创建的用户信息
     */
    @POST("/users")
    Call<User> createUser(@Body User user);

    /**
     * 更新用户
     * 
     * @param id 用户 ID
     * @param user 用户信息
     * @return 更新后的用户信息
     */
    @PUT("/users/{id}")
    Call<User> updateUser(@Path("id") Long id, @Body User user);

    /**
     * 删除用户
     * 
     * @param id 用户 ID
     */
    @DELETE("/users/{id}")
    Call<Void> deleteUser(@Path("id") Long id);

    /**
     * 带查询参数的用户搜索
     * 
     * @param name 用户名
     * @param email 邮箱
     * @return 用户列表
     */
    @GET("/users")
    Call<List<User>> searchUsers(@Query("name") String name, @Query("email") String email);

    /**
     * 使用查询参数 Map
     * 
     * @param params 查询参数
     * @return 用户列表
     */
    @GET("/users")
    Call<List<User>> searchUsersWithMap(@QueryMap Map<String, Object> params);

    /**
     * 带自定义 Header 的请求
     * 
     * @param authorization 认证头
     * @param id 用户 ID
     * @return 用户信息
     */
    @GET("/users/{id}")
    Call<User> getUserWithAuth(@Header("Authorization") String authorization, @Path("id") Long id);

    /**
     * 带多个 Header 的请求
     * 
     * @param id 用户 ID
     * @return 用户信息
     */
    @Headers({
        "User-Agent: SpringBoot-Retrofit-Demo/1.0",
        "Accept: application/json"
    })
    @GET("/users/{id}")
    Call<User> getUserWithHeaders(@Path("id") Long id);

    /**
     * 带重试机制的请求
     * 
     * @param id 用户 ID
     * @return 用户信息
     */
    @Retry(maxRetries = 3, intervalMs = 1000)
    @GET("/users/{id}")
    Call<User> getUserWithRetry(@Path("id") Long id);

    /**
     * 动态 URL 请求
     * 
     * @param url 完整的 URL
     * @return 用户信息
     */
    @GET
    Call<User> getUserByUrl(@Url String url);
} 